/**
 * Copyright (c) 2009 Blue Whale Systems Ltd
 * 
 * This software is provided "as is," and the copyright holder makes no representations or warranties, express or
 * implied, including but not limited to warranties of merchantability or fitness for any particular purpose or that the
 * use of this software or documentation will not infringe any third party patents, copyrights, trademarks or other
 * rights.
 * 
 * The copyright holder will not be liable for any direct, indirect special or consequential damages arising out of any
 * use of this software or documentation.
 */
package com.bluewhalesystems.client.lwuit.richtext;

import com.sun.lwuit.Painter;

/**
 * Describes the data structure and storage interface for content displayed using {@link com.sun.lwuit.RichTextArea}.
 */
public interface RichTextAreaModel
{
    /**
     * Expected data version (the value at index 0).
     */
    char DATA_VERSION                            = 'A';

    /**
     * When {@link #getData(int, int, int[])} returns, the parameter at this index will contain the length of valid 
     * data within the returned char[]. The data is stored in a 'growable' buffer so at any one time not all of it
     * may be usable and valid.
     */
    int  PARAMETER_VALID_LENGTH                  = 0;

    /**
     * When {@link #getData(int, int, int[])} returns, the parameter at this index will contain the suggested offset
     * for the provided scroll position (if any). This is an optional operation and the value may not be useful. But it
     * is guaranteed to be valid.
     */
    int  PARAMETER_OFFSET_FOR_POSITION           = 1;

    /**
     * When {@link #getData(int, int, int[])} returns, the parameter at this index will contain the height (the 
     * absolute y-position) of the data starting at the offset. Guaranteed to be valid.
     */
    int  PARAMETER_HEIGHT_AT_OFFSET_FOR_POSITION = 2;

    /**
     * Returns the data to be rendered for the given width. This array contains both formatting (fonts, colors, etc)
     * as well as character data.
     * 
     * @param aComponentWidth available component width
     * @param aScrollPosition current scroll position (optional)
     * @param aParameters out-parameters which will be updated by the function
     * @return data to render
     */
    char[] getData( int aComponentWidth, int aScrollPosition, int[] aParameters );

    /**
     * Returns the height (in pixels) for the given width. This may be an estimate.
     * 
     * @return how tall the component needs to be to render all the data
     */
    int getComponentHeight( int aComponentWidth );

    /**
     * Provides a {@link Painter} for the embedded object specified by an id.
     * 
     * @param aId embedded object id
     * @return painte for the embedded object
     */
    Painter getObjectPainter( int aId );
}